Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

nice_things/collections/Map.sh

The Map class implements a Hash Map in pure POSIX sh. This data structure is optimized for random access over iteration. The order of insertion of keys is not preserved. The API is influenced by JavaScript Maps.

Being a class, while working with Map, you will be passing references around. The internal state of the object is managed by the framework's object system, you only have to keep a reference to it. The constructor returns a reference, and every method is this class take that reference as the first argument. The user is responsible for calling the destructor method to free the resources used by the object.

Usage examples

# Create a Map: letters={a=1,b=2}
letters=#{{{ new Map }}} a 1 b 2

# Add mappings to the Map: letters={a=1,b=2,c=3,d=4}
Map_set "$letters" c 3 d 4

# Get the values of mappings "b" and "c": value_b=2 value_c=3
Map_get "$letters" value_b b value_c c

# Destroy the Map
Map_destructor "$letters"

Map

Since 0.3.0 · Source 

import "{ Map }" from nice_things/collections/Map.sh

Synopsis
Map <&self> [<key> <value>]…

Configuration
–

Description
Constructor for the Map class. Can optionally take initial mappings as arguments in the form of <key> <value> pairs.

Usually, this constructor function should be invoked with the new macro, which takes care of creating the <&self> reference to the newly created object.

Options
–

Operands

  • <out_var>: Output variable; the result will be written to this variable.
  • <key>: Key for a new mapping.
  • <value>: Value of new mapping.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

numbers=#{{{ new Map }}} 1 one 2 two 3 three 4 four 5 five

Map_clear

Since 0.3.0 · Source 

import "{ Map_clear }" from nice_things/collections/Map_clear.sh

Synopsis
Map_clear <&self>

Configuration
–

Description
Delete all mappings and set size to 0.

Options
–

Operands
<&self>: Self reference.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

Map_clear "$map"

Map_clone

Since 0.3.0 · Source 

import "{ Map_clone }" from nice_things/collections/Map_clone.sh

Synopsis
Map_clone <&self> <out_var>

Configuration
–

Description
Clone the Map. The new Map is assigned to <out_var>.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

Map_clone "$map" clone

Map_delete

Since 0.3.0 · Source 

import "{ Map_delete }" from nice_things/collections/Map_delete.sh

Synopsis
Map_delete <&self> <out_var> <key>

Configuration
–

Description
Delete the mapping identified by <key>. The deleted value is assigned to <out_var>.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the deleted value will be written to this variable. You can set this to the null string if you don't need the deleted value.
  • <key>: Key of mapping to delete.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 1: <key> does not exist in the Map.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

numbers=#{{{ new Map }}} 1 one 2 two 3 three 4 four 5 five
Map_delete "$numbers" deleted 3
log_debug "Deleted value: '${deleted}'" # three

Map_destructor

Since 0.3.0 · Source 

import "{ Map_destructor }" from nice_things/collections/Map_destructor.sh

Synopsis
Map_destructor <&self>

Configuration
–

Description
Clear all data associated with the object.

Options
–

Operands
<&self>: Self reference.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

Map_destructor "$map"

Map_get

Since 0.3.0 · Source 

import "{ Map_get }" from nice_things/collections/Map_get.sh

Synopsis
Map_get <&self> [<out_var> <key>]…

Configuration
–

Description
Get values from the Map by key.

Multiple values can be retrieved with a single invocation. If any <key> does not exist in the Map, status code 1 will be returned and the variable named by its <out_var> argument will be unset.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the value will be written to this variable.
  • <key>: Key of the value to retrieve.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 1: One or more <key> does not exist in the Map.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

numbers=#{{{ new Map }}} 1 one 2 two 3 three 4 four 5 five
if Map_get "$numbers" value 3; then
	log_debug "Got value: '${value}'" # three
else
	log_debug "Mapping '3' does not exist"
fi

Map_has

Since 0.3.0 · Source 

import "{ Map_has }" from nice_things/collections/Map_has.sh

Synopsis
Map_has <&self> <key>

Configuration
–

Description
Test if <key> exists in the Map. Return status code 0 if true, 1 if false.

Options
–

Operands

  • <&self>: Self reference.
  • <key>: The key to search.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: <key> exists in the Map.
  • 1: <key> does not exist in the Map.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

numbers=#{{{ new Map }}} 1 one 2 two 3 three 4 four 5 five
if Map_has "$numbers" 3; then
	log_debug "'3' exists"
fi

Map_set

Since 0.3.0 · Source 

import "{ Map_set }" from nice_things/collections/Map_set.sh

Synopsis
Map_set <&self> [<key> <value>]…

Configuration
–

Description
Add mappings to the Map. Several mappings can be added with a single invocation.

Options
–

Operands

  • <&self>: Self reference.
  • <key>: The key to add.
  • <value>: The value to add.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

numbers=#{{{ new Map }}} 1 one 2 two 3 three
Map_set "$numbers" 4 four 5 five

Map_size

Since 0.3.0 · Source 

import "{ Map_size }" from nice_things/collections/Map_size.sh

Synopsis
Map_size <&self> <out_var>

Configuration
–

Description
Get the size of the Map.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

numbers=#{{{ new Map }}} 1 one 2 two 3 three 4 four 5 five
Map_size "$numbers" size
log_debug "Numbers size: '${size}'" # 5

Map_to_quoted

Since 0.3.0 · Source 

import "{ Map_to_quoted }" from nice_things/collections/Map_to_quoted.sh

Synopsis
Map_to_quoted <&self> <out_var>

Configuration
–

Description
Get a quoted textual representation of the Map that is appropriate to use as an argument to the eval builtin command.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

Map_to_quoted "$map" quoted_map